<?php

namespace pmvc\data\sql;

use pmvc\tx\Transaction;
use pmvc\tx\TransactionProvider;

/**
 * A simple database abstraction layer.
 *
 */
interface DataSource
	extends TransactionProvider {

	/**
	 * Connects to the data source.
	 * 
	 * @return bool true if connected, false otherwise
	 */
	function connect();

	/**
	 * Escapes a string for use in a SQL query.
	 * 
	 * @param string $str
	 * @return string the escaped string
	 */
	function escape($str);

	/**
	 * Executes a query.  The first parameter is
	 * the SQL query, subsequent parameters are 
	 * tokens to be escaped and added to the query
	 * by index.  IE:
	 * <code>
	 * $ds->query("select * from table where id={0} and name={1}", 12, "Mosefus");
	 * </code>
	 * The return value is used for retreiving results
	 * from the datasource, ie: {@link #fetchRowObjects}.
	 * 
	 * @param string $sql
	 * @param mixed $arguments,...
	 * @return mixed
	 */
	function query();

	/**
	 * Executes a query.  The first parameter is
	 * the SQL query, the second parameter is an
	 * associative array of tokens to be escaped
	 * and added to the query.  IE:
	 * <code>
	 * $ds->query("select * from table where id={id} and name={name}", Array("id"=>12, name=>"Mosefus"));
	 * </code>
	 * The return value is used for retreiving results
	 * from the datasource, ie: {@link #fetchRowObjects}.
	 * 
	 * @param string $sql
	 * @param array $params
	 * @return mixed
	 */
	function queryParams($sql, $params);

	/**
	 * Executes a query.  The first parameter is
	 * the SQL query, subsequent parameters are 
	 * tokens to be escaped and added to the query
	 * by index.  IE:
	 * <code>
	 * $ds->update("update table set name={1} where id={0}", 12, "Mosefus");
	 * </code>
	 * 
	 * @param string $sql
	 * @param mixed $arguments,...
	 */
	function update();

	/**
	 * Executes a query.  The first parameter is
	 * the SQL query, the second parameter is an
	 * associative array of tokens to be escaped
	 * and added to the query.  IE:
	 * <code>
	 * $ds->update("update table set name={name} where id={id}", Array("id"=>12, name=>"Mosefus");
	 * </code>
	 * 
	 * @param string $sql
	 * @param array $params
	 * @return mixed
	 */
	function updateParams($sql, $params);

	/**
	 * Executes a query returning a single result. 
	 * The first parameter is the SQL query, subsequent
	 * parameters are tokens to be escaped and added to 
	 * the query by index.  IE:
	 * <code>
	 * $ds->querySingle("select * from table where id={0} and name={1}", 12, "Mosefus");
	 * </code>
	 * 
	 * @param string $sql
	 * @param mixed $arguments,...
	 * @return mixed
	 */
	function querySingle();

	/**
	 * Executes a query returning a single result. 
	 * The first parameter is the SQL query, the second
	 * parameter is an associative array of tokens to
	 * be escaped and added to the query.  IE:
	 * <code>
	 * $ds->querySingle("select * from table where id={id} and name={name}", Array("id"=>12, name=>"Mosefus"));
	 * </code>
	 * 
	 * @param string $sql
	 * @param array $params
	 * @return mixed
	 */
	function querySingleParams($sql, $params);

	/**
	 * Executes a query returning multiple results. 
	 * The first parameter is the SQL query, the second
	 * parameter is an associative array of tokens to
	 * be escaped and added to the query.  IE:
	 * <code>
	 * $ds->queryMultiple("select * from table where name={0}", "Mosefus");
	 * </code>
	 * 
	 * @param string $sql
	 * @param mixed $arguments,...
	 * @return array
	 */
	function queryMultiple();

	/**
	 * Executes a query returning multiple results. 
	 * The first parameter is the SQL query, the second
	 * parameter is an associative array of tokens to
	 * be escaped and added to the query.  IE:
	 * <code>
	 * $ds->queryMultiple("select * from table where name={name}", Array(name=>"Mosefus"));
	 * </code>
	 * 
	 * @param string $sql
	 * @param array $params
	 * @return array
	 */
	function queryMultipleParams($sql, $params);
	
	/**
	 * Returns the ID of the last inserted record.
	 * 
	 * @return int the id
	 */
	function lastInsertId();
	
	/**
	 * Returns the number of rows that the given
	 * query result has or -1 if the data source
	 * doesnt' support it.
	 * 
	 * @param int $res the query resoult
	 * @return int the number of rows or -1 if not supported
	 */
	function numberOfRows($res);
	
	/**
	 * Returns the number of rows that the given
	 * query result affected or -1 if the data source
	 * doesnt' support it.
	 * 
	 * @param int $res the query resoult
	 * @return int the number of rows or -1 if not supported
	 */
	function numberOfAffectedRows($res);
	
	/**
	 * Returns the next record from the given query
	 * result as an object.  This method moves the
	 * result pointer to the next object in the result
	 * so that subsequent calls return the next object
	 * until there are none left.
	 * 
	 * @param $res
	 * @return object
	 */
	function fetchRowObject($res);
	
	/**
	 * Returns all of the records from the given query
	 * result as an array of objects.
	 * 
	 * @param $res
	 * @param array
	 */
	function fetchRowObjects($res);
	
	/**
	 * Frees the given query result.
	 * 
	 * @param $res
	 */
	function freeResult($res);

	/**
	 * Returns the last error message if any.
	 * @return string
	 */
	function getLastError();
	
}
?>